# 
Style Camera

Copyright © Quectel Wireless Solutions Co., Ltd. 2026. All rights reserved.

---

This project is an AI style camera sample built on the Quectel Pi M2 smart mainboard.

The system captures live video through a USB camera and runs artistic style-transfer models and a human pose model on the on-board NPU, providing 11 real-time effects — 7 artistic styles (Hayao, oil painting, candy, glass mosaic, sketch, ukiyo-e and ink painting) plus 4 fun stickers (dog, pig, rabbit and clown head) positioned by human body keypoints. It demonstrates the end-to-end pipeline of "video capture → real-time NPU stylization → one-press photo saving". The GUI previews the stylized picture in real time; press the space bar to save a stylized photo, and open the photo folder directly from the thumbnail.

> It is recommended to insert an application photo here (UI running view + effect comparison) as the cover.

## Developer Resources

### Accessory List

> Note: tips — The accessory list is for reference only; actual requirements may vary with the development environment.

[电子表格]

### Accessory Photos

> It is recommended to insert a photo of the accessories here.

## Quick Start

### Preparation

The Quectel Pi M2 smart mainboard ships with the Debian 13 image by default, so there is no need to flash the image again — simply follow the steps below. The NPU runtime library, the Python 3.12 environment and all dependencies are installed automatically by the one-click deployment script bundled in the repository.

### Hardware Connection

Complete all of the following hardware connections:

1. **Camera**: plug the USB camera into the USB-A port of the mainboard. Use v4l2-ctl --list-devices to check the device index (on the reference unit, PC Camera = /dev/video73); if it differs from the configuration, override it with the --camera N option.

2. **Display (optional)**: connect an HDMI monitor to view the GUI locally; without a monitor, run in headless mode.

3. **Network**: connect an Ethernet cable for SSH login and code cloning.

4. **Power**: connect the Type-C power adapter and power on.

> Note: tips — This project does not require audio peripherals such as a microphone or speaker. After connection, verify that the camera is present with v4l2-ctl --list-devices, or run --test-camera to measure the actual capture frame rate.

## Project Implementation

### Get the Code

Open a terminal on the mainboard and clone the project code with git.

```plaintext
sudo apt update
sudo apt install -y git
git clone https://github.com/Quectel-Pi/demo_style_camera.git
cd demo_style_camera
```

After the command completes, enter the demo_style_camera directory, which contains all source code of this project.

### Environment Setup

Run the one-click deployment script bundled in the repository to automatically install a standalone Python 3.12 environment, inference dependencies and the RKNN runtime library:

```plaintext
sudo bash deploy/board_setup.sh
```

The script supports both **online and offline modes**: in online mode, Python 3.12 and pip dependencies are installed via uv; in offline mode, the wheels and offline Python packages shipped with the bundle are used. It also installs the NPU runtime librknnrt.so into the system directory.

> Note: tips — All on-board dependencies are installed into the standalone /opt/py312 environment created by the deployment script. Do not run this project with the system python3 (it raises ModuleNotFoundError). run.sh locates the environment automatically — always launch the program through run.sh.

### Self-Test

Before the first run, it is recommended to run the built-in self-checks in order to confirm that the hardware and software links work properly:

```plaintext
/opt/py312/bin/python3.12 selftest.py    # Offline self-test: model loading / effect pipeline, no camera needed
sudo ./run.sh --test-camera              # Camera test: measures the actual capture frame rate for 5 seconds
sudo ./run.sh --list-styles              # Lists all currently available effects
sudo ./run.sh --test-style any.jpg       # Runs all effects on any static image and saves the results
```

### Run the Program

```plaintext
sudo ./run.sh
```

run.sh automatically locates the deployment directory and the Python environment, sets up the desktop display permissions and starts the program. If the program starts properly, a "Style Camera" window pops up, with the live effect preview on the left and the effect selection panel on the right.

For scenarios without a monitor, run in headless mode:

```plaintext
sudo ./run.sh --no-ui
```

### UI and Features

After the program starts normally, the preview defaults to the raw picture (about 25 fps); click an effect button on the right to switch effects in real time, and press the space bar to take a photo.

[电子表格]

**Shortcuts**: in the GUI, press the space bar to take a photo; in the OpenCV fallback window, the space bar takes a photo, s cycles through effects, and q quits.

### Effects Overview

All effects run on the NPU (the corresponding mode is hidden automatically when its model file is missing):

[电子表格]

### Photo Storage

After pressing the space bar, photos are saved automatically to the photos/ directory:

- style_YYYYMMDD_HHMMSS.jpg: the stylized picture (JPEG quality 95);

- orig_time.jpg: the original picture at the original resolution (enabled when save.save_original: true in config.yaml).

Captures are completed through a dedicated photo-writing thread plus a queue, without blocking the preview.

### How It Works

System data flow: 720p@30fps MJPG capture → stylization thread (art style modes: the image is scaled to the model input size and sent to the NPU for inference, and the result is pasted back onto the original frame; sticker modes: YOLOv8-Pose detects facial keypoints and the sticker PNG is scaled and aligned to the keypoint positions) → UI thread renders the preview / the capture thread enqueues the photo.

The three threads (capture and stylization, photo writing, UI) are decoupled from each other: the preview always stays smooth and photo taking never stutters. All style-transfer models take a unified 192×192 input (oil painting 224, Hayao 160); the normalization parameters are baked into the RKNN models, so the board can feed RGB images directly.

Model files are located in the models/ directory (7 style-transfer models + 1 pose model, all in RK3576 NPU fp16 format); to convert or replace a style model by yourself, refer to the conversion scripts under the tools/ directory.

### Application Demo

> It is recommended to insert an application demo video here (live effect switching + space bar photo capture).

## Frequently Asked Questions and Solutions

### Program cannot find the camera

Symptom:

```plaintext
Camera open failed
```

Solutions:

- Confirm the camera device index with v4l2-ctl --list-devices;

- Change camera.index in config.yaml, or specify it at runtime with the --camera N option (73 on the reference unit of this project).

### Effect button missing / mode unavailable

Symptom: an effect button does not appear in the UI.

Solutions:

- The mode hides itself automatically when the corresponding RKNN model file is missing; check whether the corresponding .rknn file under models/ is complete (an incomplete git clone or later cleanup may remove it);

- Run sudo ./run.sh --list-styles to check the list of effects actually available.

### GUI fails to start

Symptom: after running in a desktop environment no window pops up, and the program falls back to command-line mode.

Solutions:

- Start with sudo ./run.sh; the script already handles the display permissions under the Wayland desktop (DISPLAY / XAUTHORITY / QT_QPA_PLATFORM);

- If the log says the Qt xcb plugin failed to load, install the missing system library: sudo apt install -y libxcb-cursor0 (the deployment script has a built-in automatic fallback installation);

- For scenarios without a monitor, use sudo ./run.sh --no-ui directly.

### NPU inference error or model loading failure

Symptom:

```plaintext
RKNN run error / librknnrt version mismatch
```

Solutions:

- Make sure librknnrt.so matches the on-board rknn-toolkit-lite2 version (re-running the deployment script aligns them automatically);

- Make sure the model files are .rknn files compiled for the RK3576 target platform (bundled in the models/ directory of the project);

- For debugging on a PC, run python3 main.py --config config_onnx_debug.yaml --test-style any.jpg to verify the pipeline with CPU inference.

## Technical Support and Contribution

If you encounter any problems during use, feel free to submit a technical request on the Quectel official forum; our technical support team will answer you promptly.

Project open-source address: https://github.com/Quectel-Pi/demo_style_camera

Issues and Pull Requests for code improvements are welcome!